---
title: Lua Reference - kong.dao
layout: default
---


<header class="page-header">
  <div class="container">
    <div class="page-header-icon">
      <img src="/assets/images/icons/icn-documentation.svg" alt="Documentation" />
    </div>
    <div class="page-header-title">
      <h1>Public Lua API Reference</h1>
      <p>For plugins developers and core contributors</p>
    </div>
    {% if site.data.kong_versions.size > 1 %}
      {% include lua-reference-dropdown.html
        page=page
        site=site
      %}
    {% endif %}
  </div>
</header>

<div class="container">
  <aside class="page-navigation">
    <nav>
      <ul>
        <li>
          <a href="/{{page.kong_version}}"><h5>Back to docs</h5></a>
        </li>
        <li>
          <a href="/{{page.kong_version}}/lua-reference/"><h5>Index</h5></a>
        </li>
        <li>
          <h5>Modules</h5>
          <ul>
            <li>kong.dao</li>
            <li><a href="../../modules/kong.plugins.basic-auth.crypto">kong.plugins.basic-auth.crypto</a></li>
            <li><a href="../../modules/kong.plugins.galileo.alf">kong.plugins.galileo.alf</a></li>
            <li><a href="../../modules/kong.plugins.galileo.buffer">kong.plugins.galileo.buffer</a></li>
            <li><a href="../../modules/kong.plugins.jwt.jwt_parser">kong.plugins.jwt.jwt_parser</a></li>
            <li><a href="../../modules/kong.tools.responses">kong.tools.responses</a></li>
            <li><a href="../../modules/kong.tools.timestamp">kong.tools.timestamp</a></li>
            <li><a href="../../modules/kong.tools.utils">kong.tools.utils</a></li>
            <li><a href="../../modules/spec.helpers">spec.helpers</a></li>
          </ul>
        </li>
      </ul>
    </nav>
  </aside>

  <div class="page-content-container">
  <div class="page-content">
    <div class="content">
<h1><code>kong.dao</code></h1>
<p>Operates over entities of a given type in a database table.</p>
<p>An instance of this class is to be instantiated for each entity, and can interact
 with the table representing the entity in the database.</p>

<p> Instantiations of this class are managed by the DAO Factory.</p>

<p> This class provides an abstraction for various databases (PostgreSQL, Cassandra)
 and is responsible for propagating clustering events related to data invalidation,
 as well as foreign constraints when the underlying database does not support them
 (as with Cassandra).</p>


<h3>Info:</h3>
<ul>
</ul>

<h2><a href="#Functions">Functions</a></h2>
<table class="function_list">
  <tr>
    <td class="name"><a href="#DAO:count">DAO:count (tbl)</a></td>
    <td class="summary">Count the number of rows.</td>
  </tr>
  <tr>
    <td class="name"><a href="#DAO:delete">DAO:delete (tbl)</a></td>
    <td class="summary">Delete a row.</td>
  </tr>
  <tr>
    <td class="name"><a href="#DAO:find">DAO:find (tbl)</a></td>
    <td class="summary">Find a row.</td>
  </tr>
  <tr>
    <td class="name"><a href="#DAO:find_all">DAO:find_all (tbl)</a></td>
    <td class="summary">Find all rows.</td>
  </tr>
  <tr>
    <td class="name"><a href="#DAO:find_page">DAO:find_page (tbl, page_offset, page_size)</a></td>
    <td class="summary">Find a paginated set of rows.</td>
  </tr>
  <tr>
    <td class="name"><a href="#DAO:insert">DAO:insert (tbl, options)</a></td>
    <td class="summary">Insert a row.</td>
  </tr>
  <tr>
    <td class="name"><a href="#DAO:new">DAO:new (db, model_mt, schema, constraints)</a></td>
    <td class="summary">Instantiate a DAO.</td>
  </tr>
  <tr>
    <td class="name"><a href="#DAO:update">DAO:update (tbl, filter_keys, options)</a></td>
    <td class="summary">Update a row.</td>
  </tr>
</table>


<h2 class="section-header "><a name="Functions">Functions</a></h2>


<dl class="function">
  <hr />
  <dt>
    <h4><a name="DAO:count">DAO:count</a></h4>
  </dt>
  <dd>
    Count the number of rows.
 Count the number of rows matching the given values.

    <h5>Parameters:</h5>
    <ul>
        <li>
          <code class="parameter">tbl</code>
          <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
          (optional) A table containing the fields and values to filter for.
        </li>
    </ul>

    <h5>Returns:</h5>
    <ul>
      <li>
        <span class="types"><span class="type">number</span></span>
        count The total count of rows matching the given filter, or total count of rows if no filter was given.
      </li>
      <li>
        <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
        err If an error occurred, a table describing the issue.
      </li>
    </ul>





  </dd>
  <hr />
  <dt>
    <h4><a name="DAO:delete">DAO:delete</a></h4>
  </dt>
  <dd>
    Delete a row.
 Delete a row in table related to this instance. Also deletes all rows with a relashionship to the deleted row
 (via foreign key relations). For SQL databases such as PostgreSQL, the underlying implementation
 leverages "FOREIGN KEY" constraints, but for others such as Cassandra, such operations are executed
 manually.

    <h5>Parameters:</h5>
    <ul>
        <li>
          <code class="parameter">tbl</code>
          <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
          A table containing the primary key field(s) for this row.
        </li>
    </ul>

    <h5>Returns:</h5>
    <ul>
      <li>
        <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
        row A table representing the deleted row
      </li>
      <li>
        <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
        err If an error occurred, a table describing the issue.
      </li>
    </ul>





  </dd>
  <hr />
  <dt>
    <h4><a name="DAO:find">DAO:find</a></h4>
  </dt>
  <dd>
    Find a row.
 Find a row by its given, mandatory primary key. All other fields are ignored.

    <h5>Parameters:</h5>
    <ul>
        <li>
          <code class="parameter">tbl</code>
          <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
          A table containing the primary key field(s) for this row.
        </li>
    </ul>

    <h5>Returns:</h5>
    <ul>
      <li>
        <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
        row The row, or nil if none could be found.
      </li>
      <li>
        <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
        err If an error occurred, a table describing the issue.
      </li>
    </ul>





  </dd>
  <hr />
  <dt>
    <h4><a name="DAO:find_all">DAO:find_all</a></h4>
  </dt>
  <dd>
    Find all rows.
 Find all rows in the table, eventually matching the values in the given fields.

    <h5>Parameters:</h5>
    <ul>
        <li>
          <code class="parameter">tbl</code>
          <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
          (optional) A table containing the fields and values to search for.
        </li>
    </ul>

    <h5>Returns:</h5>
    <ul>
      <li>
        <span class="types"><span class="type">rows</span></span>
        An array of rows.
      </li>
      <li>
        <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
        err If an error occurred, a table describing the issue.
      </li>
    </ul>





  </dd>
  <hr />
  <dt>
    <h4><a name="DAO:find_page">DAO:find_page</a></h4>
  </dt>
  <dd>
    Find a paginated set of rows.
 Find a pginated set of rows eventually matching the values in the given fields.

    <h5>Parameters:</h5>
    <ul>
        <li>
          <code class="parameter">tbl</code>
          <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
          (optional) A table containing the fields and values to filter for.
        </li>
        <li>
          <code class="parameter">page_offset</code>
          Offset at which to resume pagination.
        </li>
        <li>
          <code class="parameter">page_size</code>
          Size of the page to retrieve (number of rows).
        </li>
    </ul>

    <h5>Returns:</h5>
    <ul>
      <li>
        <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
        rows An array of rows.
      </li>
      <li>
        <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
        err If an error occurred, a table describing the issue.
      </li>
    </ul>





  </dd>
  <hr />
  <dt>
    <h4><a name="DAO:insert">DAO:insert</a></h4>
  </dt>
  <dd>
    Insert a row.
 Insert a given Lua table as a row in the related table.

    <h5>Parameters:</h5>
    <ul>
        <li>
          <code class="parameter">tbl</code>
          <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
          Table to insert as a row.
        </li>
        <li>
          <code class="parameter">options</code>
          <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
          Options to use for this insertion. (<code>ttl</code>: Time-to-live for this row, in seconds, <code>quiet</code>: does not send event)
        </li>
    </ul>

    <h5>Returns:</h5>
    <ul>
      <li>
        <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
        res A table representing the insert row (with fields created during the insertion).
      </li>
      <li>
        <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
        err If an error occurred, a table describing the issue.
      </li>
    </ul>





  </dd>
  <hr />
  <dt>
    <h4><a name="DAO:new">DAO:new</a></h4>
  </dt>
  <dd>
    Instantiate a DAO.
 The DAO Factory is responsible for instantiating DAOs for each entity.
 This method is only documented for clarity.

    <h5>Parameters:</h5>
    <ul>
        <li>
          <code class="parameter">db</code>
          An instance of the underlying database object (<code>cassandra_db</code> or <code>postgres_db</code>)
        </li>
        <li>
          <code class="parameter">model_mt</code>
          The related model metatable. Such metatables contain, among other things, validation methods.
        </li>
        <li>
          <code class="parameter">schema</code>
          The schema of the entity for which this DAO is instantiated. The schema contains crucial information about how to interact with the database (fields type, table name, etc...)
        </li>
        <li>
          <code class="parameter">constraints</code>
          A table of constraints built by the DAO Factory. Such constraints are mostly useful for databases without support for foreign keys. SQL databases handle those constraints natively.
        </li>
    </ul>

    <h5>Returns:</h5>
    <ul>
      <li>
        self
      </li>
    </ul>





  </dd>
  <hr />
  <dt>
    <h4><a name="DAO:update">DAO:update</a></h4>
  </dt>
  <dd>
    Update a row.
 Update a row in the related table. Performe a partial update by default (only fields in <code>tbl</code> will)
 be updated. If asked, can perform a "full" update, replacing the entire entity (assuming it is valid)
 with the one specified in <code>tbl</code> at once.

    <h5>Parameters:</h5>
    <ul>
        <li>
          <code class="parameter">tbl</code>
          <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
          A table containing the new values for this row.
        </li>
        <li>
          <code class="parameter">filter_keys</code>
          <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
          A table which must contain the primary key(s) to select the row to be updated.
        </li>
        <li>
          <code class="parameter">options</code>
          <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
          Options to use for this update. (<code>full</code>: performs a full update of the entity, <code>quiet</code>: does not send event).
        </li>
    </ul>

    <h5>Returns:</h5>
    <ul>
      <li>
        <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
        res A table representing the updated entity.
      </li>
      <li>
        <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
        err If an error occurred, a table describing the issue.
      </li>
    </ul>





  </dd>
</dl>


    </div>
  </div>
</div>
</div>
